\chapter{Tutorial}

\section{Interpreter}

Start up durexForth. If loaded successfully, it will greet you with a friendly \texttt{ok}. You have landed in the interpreter!

Let's warm it up a little. Enter \texttt{1} (followed by return). You have now put a digit on the stack. This can be verified by the command \texttt{.s}, which will print out the stack. Now enter \texttt{.} to pop the digit and print it to screen, followed by \texttt{.s} to verify that the stack is empty.

Now some arithmetics. \texttt{1000 a * .} will calculate $\$a \times \$1000$ and print the result on the screen. \texttt{6502 100 / 1- .} will calculate and print $(\$6502 / \$100) - 1$.

Let's define a word \texttt{bg!} for setting the border color\ldots 

\begin{verbatim}
: bg! d020 c! ;
\end{verbatim}

Now try entering \texttt{1 bg!} to change the border color to white.
Then, try changing it back again with \texttt{0 bg!}.

\section{Editor}

The editor (fully described in chapter \ref{editor}) is convenient for editing larger pieces of code. With it, you keep an entire source file loaded in RAM, and you can recompile and test it easily.

Start the editor by typing \texttt{vi}. You will enter the pink editor screen.

To enter text, first press \texttt{i} to enter insert mode. This mode allows you to insert text into the buffer. You can see that it's active on the \texttt{I} that appears in the lower left corner.

This is a good start for making a program. 
But first, let's get rid of the "bg!" word we created previously. Enter:

\begin{verbatim}
forget bg!
\end{verbatim}

\ldots and press $\leftarrow$ to leave insert mode. The line you entered forgets the \texttt{bg!} word that you defined in the last section, and everything defined after it. Let's try out if it works.

First, quit the editor by pressing \texttt{:q}. You should now be back in the interpreter screen.
Verify that the word \texttt{bg!} still exists by  entering \texttt{0 bg!}, \texttt{1 bg!} like you did
before. Then, jump back to the editor using the command \texttt{vi}. You should return to your edit buffer with the lonely \texttt{forget bg!} line.

Now, compile and run the buffer by pressing \texttt{F7}. You will be thrown out to the interpreter
again. Entering \texttt{bg!} should now give you the error \colorbox{yellow}{\texttt{bg!?}}. Success
--- we have forgotten the \texttt{bg!} word. Now, get back into the editor by entering \texttt{vi}.

Beneath \texttt{forget bg!}, add the following lines:

\begin{verbatim}
: flash d020 c@ 1+ d020 c! recurse ;
flash
\end{verbatim}

\texttt{flash} will cycle the border color infinitely. Before trying it out, go up and change \texttt{forget bg!} to \texttt{forget flash}. This makes sure you won't run out of RAM, no matter how many times you recompile the program. Now press \texttt{F7} to compile and run. If everything is entered right, you will be facing a wonderful color cycle.

To get back into the editor, press Restore key. Let's see how we can factor the program to get something more Forth'y:

\begin{verbatim}
forget bg
: bg d020 ; # border color addr
: inc dup c@ 1+ swap c! ; ( addr -- )
: flash bg inc recurse ;
flash
\end{verbatim}

(Note: Parentheses are used for multi-line comments or describing arguments and return values. \texttt{\#} is used for single-line comments.)

Of course, it is a matter of taste which version you prefer. Press \texttt{F7} to see if the new version runs faster or slower.

\section{Assembler}

If you need to flash as fast as possible, use the assembler:

\begin{verbatim}
:asm flash
here # push current addr
d020 inc,
jmp, # jump to pushed addr
;asm
flash
\end{verbatim}

\texttt{:asm} and \texttt{;asm} define a code word, just like \texttt{:} and \texttt{;} define Forth words. Within a code word, you can use assembler mnemonics. 

Note: As the x register contains the durexForth stack depth, it is important that it remains unchanged at the end of the code word.

\section{Console I/O Example}

This piece of code reads from keyboard and sends back the chars to screen:

\begin{verbatim}
: foo key emit recurse ;
foo
\end{verbatim}

\section{Avoiding Stack Crashes}

durexForth should be one of the fastest and leanest Forths for the C64. To achieve this, there are
not too many niceties for beginners. For example, compiled code has no checks for stack overflow
and underflow. This means that the system may crash if you do too many pops or pushes. This is not
much of a problem for an experienced Forth programmer, but until you reach that stage, handle the
stack with care.

\subsection{Commenting}

One helpful technique to avoid stack crashes is to add comments about stack usage.
In this example, we imagine a graphics word "drawbox" that draws a black box.
\texttt{( color -- )} indicates that it takes one argument on stack, and on exit it should
leave nothing on the stack. The comments inside the word indicate what the stack
looks like after the line has executed.

\begin{verbatim}
: drawbox ( color -- )
10 begin dup 20 < while # color x
10 begin dup 20 < while # color x y
2dup # color x y x y
4 pick # color x y x y color
blkcol # color x y
1+ repeat drop # color x
1+ repeat 2drop ;
\end{verbatim}

Once the word is working, it may be nice to again remove the \texttt{\#} comments as
they are no longer very interesting to read.

\subsection{Stack Checks}

Another useful technique during development is to check at the end of your main loop
that the stack depth is what you expect it to. This will catch stack underflows
and overflows.

\begin{verbatim}
: mainloop begin
# do stuff here...
sp@ sp0 <> if ." err" exit then
again ;
\end{verbatim}

\section{Configuring durexForth}

\subsection{Stripping Modules}

By default, durexForth boots up with all modules pre-compiled in RAM:

\begin{description}
\item[doloop] Do-loop words.
\item[debug] Words for debugging.
\item[asm] The assembler.
\item[vi] The text editor.
\item[ls] List disk contents.
\item[gfx] Graphics module.
\end{description}

To reduce RAM usage, you may make a stripped-down version of durexForth. Do this by following these steps:

\begin{enumerate}
\item Issue \texttt{forget modules} to forget all modules.
\item Optionally re-add the \texttt{modules} marker with \texttt{header modules}.
\item One by one, load the modules you want included with your new Forth. (E.g. \texttt{s" debug" load})
\item Save the new system with e.g. \texttt{s" acmeforth" save-forth}.
\end{enumerate}

\subsection{Custom Start-Up}

You may launch a word automatically at start-up by setting the variable \texttt{start} to the execution token of the word.  Example: \texttt{' megademo start !}

To save the new configuration to disk, use \texttt{save-forth}.

\section{How to Learn More}

\subsection{Internet Resources}

\subsubsection{Books and Papers}

\begin{itemize}
\item \href{http://www.forth.com/starting-forth/}{Starting Forth}
\item \href{http://thinking-forth.sourceforge.net/}{Thinking Forth}
\item \href{http://www.bradrodriguez.com/papers/}{Moving Forth: a series on writing Forth kernels}
\item \href{http://www.csbruce.com/~csbruce/cbm/transactor/v7/i5/p058.html}{Blazin' Forth --- An inside look at the Blazin' Forth compiler}
\item \href{http://www.drdobbs.com/architecture-and-design/the-evolution-of-forth-an-unusual-langua/228700557}{The Evolution of FORTH, an unusual language}
\item \href{http://galileo.phys.virginia.edu/classes/551.jvn.fall01/primer.htm}{A Beginner's Guide to Forth}
\end{itemize}

\subsubsection{Other Forths}

\begin{itemize}
\item \href{http://www.colorforth.com/cf.html}{colorForth}
\item \href{http://www.annexia.org/forth}{JONESFORTH}
\item \href{http://colorforthray.info/}{colorForthRay.info --- How\_to: with Ray St. Marie}
\end{itemize}

\subsection{Other}

\begin{itemize}
\item \href{http://code.google.com/p/durexforth/}{durexForth source code}
\end{itemize}
